# Updating an existing Workspace

This endpoint returns structured Workspace objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `workspaces` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: PUT /workspaces/{id}
Version: 1.0.0

## Path parameters:

  - `id` (integer, required)
    The ID of the Model.

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `account_color` (AccountColor) - Retrieves the color of the workspace. The response will include `account_color_id`, which references the data in the `account_colors` top-level key.
- `account_insights_mappings` (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include `account_insights_mapping_ids`, which references the data in the `account_insights_mappings` top-level key.
- `approver` (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include `approver_id`, which references the data in the `users` top-level key.
- `approvers` (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include `approver_ids`, which references the data in the `users` top-level key.
- `billing_milestones` (BillingMilestone) - Retrieves the billing milestones for the workspace. The response will include `billing_milestone_ids`, which references the data in the `billing_milestones` top-level key.
- `creator` (User) - Retrieves the user who created the project. The response will include `creator_id`, which references the data in the `users` top-level key. If the creator has left the project, you can use `primary_counterpart` to get the provider-side team lead.
- `current_status_report` (StatusReport) - Retrieves the most recent project status report from today. The response will include `current_status_report_id`, which references the data in the `status_reports` top-level key.
- `current_user_participation` (Participation) - Retrieves the workspace participation of the current user. The response will include `current_user_participation_ids`, which references the data in the `participations` top-level key.
- `custom_field_values` (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include `custom_field_value_ids`, which references the data in the `custom_field_values` top-level key.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `financial_viewers` (User) - Retrieves the users on the project who have financial access. The response will include `financial_viewer_ids`, which references the data in the `users` top-level key.
- `next_uncompleted_milestone` (Story) - Retrieves the next project milestone that is not complete. The response will include `next_uncompleted_milestone_id`, which references the data in the `stories` top-level key.
- `participants` (User) - Retrieves users that are participating in the project. The response will include `participant_ids`, which references the data in the `users` top-level key.
- `participations` (Participation) - Retrieves the [participations](/tag/Participations) of each participant in the project. The response will include `participation_ids`, which references the data in the `participations` top-level key.
- `possible_approvers` (User) - Retrieves the users that can be made time approvers on the workspace. The response will include `possible_approver_ids`, which references the data in the `users` top-level key.
- `primary_counterpart` (User) - Retrieves the lead of the Clients team. The response will include `primary_counterpart_id`, which references the data in the `users` top-level key.
- `primary_maven` (User) - Retrieves the lead of the Providers team. The response will include `primary_maven_id`, which references the data in the `users` top-level key.
- `primary_workspace_group` (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include `primary_workspace_group_id`, which references the data in the `workspace_groups` top-level key.
- `status_reports` (StatusReport) - Retrieves the status reports for the workspace. The response will include `status_report_ids`, which references the data in the `status_reports` top-level key.
- `timesheet_submissions` (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include `timesheet_submission_ids`, which references the data in the `timesheet_submissions` top-level key.
- `workspace_groups` (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include `workspace_group_ids`, which references the data in the `workspace_groups` top-level key.
- `workspace_resources` (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include `workspace_resource_ids`, which references the data in the `workspace_resources` top-level key.
- `workspace_resources_with_unnamed` (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include `workspace_resources_with_unnamed_ids`, which references the data in the `workspace_resources` top-level key.

  - `optional_fields` (array)
    Allows you to request one or more optional fields as an array.

## Request fields (application/json):

  - `workspace` (object)

  - `workspace.consultant_role_name` (string)
    The label for the consultant team (i.e. the team providing the service).

  - `workspace.client_role_name` (string)
    The label for the client team (i.e. the team paying for the service).

  - `workspace.budgeted` (boolean)
    Whether the project is budgeted.
Defaults to `true` for paid accounts.
Defaults to `false` for free accounts.

  - `workspace.start_date` (string)
    When the project starts. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `workspace.due_date` (string)
    When the project is due. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `workspace.description` (string)
    The description of the project.

  - `workspace.currency` (string)
    The currency of the project.
Only applicable if `budgeted` is true.
See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/360041576473) for the list of currency codes.
Defaults to the account currency or `USD`.
If a `rate_card_id` is provided, this field is ignored.

  - `workspace.access_level` (string)
    Whether the project is open, and who can join the project.
    Enum: "invitation", "open", "admins"

  - `workspace.rate_card_id` (integer)
    The ID of the rate card for the project. The currency of the rate card must match the currency of the project.

  - `workspace.exclude_archived_stories_percent_complete` (boolean)
    Whether archived tasks are excluded from the calculation of the project completion percentage.

  - `workspace.revenue_recognition_method_id` (string)
    The criteria that determines how the project's revenue is recognized and accounted for. The ID is a composite ID made up of a numerical ID (unique to each account), a colon, and the method type. For example `123:percent_complete`. Use the [fetching a list of revenue recognition methods endpoint](/kantata/specification/revenue-recognition-methods/get%20revenue%20recognition%20methods) to get the IDs specific to your account. Set to `null` to remove a workspace's revenue recognition method.

This setting is available only when the [early access feature Revenue Management](https://knowledge.kantata.com/hc/en-us/articles/38986877019803-Revenue-Management-Early-Access) is activated.

  - `workspace.revenue_recognition_method_name` (string)
    The criteria that determines how the project's revenue is recognized and accounted for. Default options are `Time & Materials`, `% Complete (Hours)`, and `% Complete (Cost)`. Set to `null` to remove a workspace's revenue recognition method.

This setting is available only when the [early access feature Revenue Management](https://knowledge.kantata.com/hc/en-us/articles/38986877019803-Revenue-Management-Early-Access) is activated.

  - `workspace.tasks_default_non_billable` (boolean)
    Whether tasks in the project default to non-billable.

  - `workspace.stories_are_fixed_fee_by_default` (boolean)
    Whether tasks in the project default to fixed fee (`true`) or time and materials (`false`).

  - `workspace.expenses_in_burn_rate` (boolean)
    Sets whether both expenses and invoice additional items should be included in the actual fees calculation for the project. Note that setting this field sets the values of both `actual_fees_includes_expenses` and `actual_fees_includes_additional_line_items`. To set the values individually, set `actual_fees_includes_expenses` and `actual_fees_includes_additional_line_items` instead.

  - `workspace.actual_fees_includes_expenses` (boolean)
    Sets whether expenses should be included in the actual fees calculation for the project.

  - `workspace.actual_fees_includes_additional_line_items` (boolean)
    Sets whether invoice additional items should be included in the actual fees calculation for the project.

  - `workspace.posts_require_privacy_decision` (boolean)
    Whether project posts are visible to everyone in the project (`false`) or are private (`true`) by default.

  - `workspace.status_key` (integer)
    The status of the project. See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/115005042433-Project-Status#Project-Status-List) for a list of project status IDs.

  - `workspace.invoice_preference` (object)
    Invoice customization preferences that will be automatically generated in each invoice for the project.

  - `workspace.invoice_preference.client_invoice_address` (string)
    The client address to automatically generate in each new invoice.

  - `workspace.invoice_preference.client_invoice_name` (string)
    The client name to automatically generate in each new invoice.

  - `workspace.invoice_preference.consultant_invoice_address` (string)
    The provider address to automatically generate in each new invoice.

  - `workspace.invoice_preference.consultant_invoice_name` (string)
    The provider name to automatically generate in each new invoice.

  - `workspace.invoice_preference.project_code` (string)
    The project code to automatically generate in each new invoice.

  - `workspace.invoice_preference.purchase_order` (string)
    The purchase order to automatically generate in each new invoice.

  - `workspace.approver_id` (integer)
    The user ID of the designated time approver for the project.

  - `workspace.workspace_group_ids` (array)
    The IDs of the [groups](/tag/Workspace-Groups) the project belongs to.

  - `workspace.project_template_start_date` (string)
    When `project_tracker_template_id` is provided, this sets the start date that tasks will be based on when the template is applied. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `workspace.project_template_checklist_as_todos` (boolean)
    Whether checklist items are converted to To Dos when applying a template.

  - `workspace.project_template_assignment_mappings` (array)
    When `project_tracker_template_id` is provided, this maps template resources to named or unnamed resources when the template is applied. If named resources are specified via the `user_id` field, the users should also be included in the `participations` field.

  - `workspace.project_template_assignment_mappings.resource_id` (integer)
    The ID of the [project template assignment](/tag/Project-Template-Assignments) this mapping is for.

  - `workspace.project_template_assignment_mappings.user_id` (integer)
    The ID of the user to map the template resource to. If you pass a `user_id` and do not set `role_id`, the workspace resource's role will be the user's default account role or—if they have none—it will be blank.

  - `workspace.project_template_assignment_mappings.role_id` (integer)
    The ID of the account role to use as the workspace role for this template resource. If you pass a `role_id` but do not pass a `user_id`, an unnamed resource will be created.

  - `workspace.project_template_weekends_as_workdays` (boolean)
    When `project_tracker_template_id` is provided, this sets whether weekends count as work days when applying the template. If `true`, weekend days will be included in task durations.

  - `workspace.project_template_create_unnamed_resources` (boolean)
    When `project_tracker_template_id` is provided, this maps all template resources and task assignments to unnamed resources, and ignores `project_template_assignment_mappings` for task assignments.

  - `workspace.project_template_distribute_hours` (boolean)
    When `project_tracker_template_id` is provided, this sets whether task estimated hours in the template are automatically added as scheduled hours for all tasks when applying the template. The hours will be distributed evenly between the task start date and end date.

  - `workspace.project_tracker_template_id` (integer)
    The ID of the template to use to populate tasks and other information in the project.

  - `workspace.primary_workspace_group_id` (integer)
    The ID of the [group](/tag/Workspace-Groups) that is the primary group for the project.

  - `workspace.target_margin` (integer)
    The desired profit, expressed as a percentage.

  - `workspace.external_reference` (object)
    Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).

  - `workspace.external_reference.service_name` (string, required)
    The provider name of the integration. If you are adding multiple external references to the same object, the `service_name` must be unique.

  - `workspace.external_reference.service_model` (string, required)
    The object type of the external object this external reference belongs to.

  - `workspace.external_reference.service_model_ref` (string, required)
    The object ID of the external object this external reference belongs to.

  - `workspace.external_reference.status` (string)
    The status of the integration. Options are `successful`, `pending`,  or `failed`.

  - `workspace.external_reference.external_message` (string)
    The message on the external object.

  - `workspace.external_reference.external_link` (string)
    The link to the external object.

  - `workspace.external_reference.external_status` (string)
    The status of the external object in the external system.

  - `workspace.external_reference.locked` (boolean)
    Whether the subject is locked.

  - `workspace.account_color_id` (integer)
    The ID of the [account color](/tag/Account-Colors) to apply to the project.

  - `workspace.external_link` (object)
    A link to display within the project workspace. Requires the Project Button facilitated feature.

  - `workspace.external_link.text` (string)
    The URL of the link.

  - `workspace.external_link.url` (string)
    The button text.

  - `workspace.account_insights_mapping_ids` (array)
    The IDs of Insights dynamic dashboards to add to the project.

  - `workspace.custom_fields` (array)
    Custom field values for the project.

  - `workspace.custom_fields.custom_field_id` (integer)
    The ID of the custom field.

  - `workspace.custom_fields.value` (string)
    The value for the corresponding custom field. The value formats for different types are:

* `string` - `<text_string>`, eg. `'foo'`
* `date` - `<ISO_8601 Date Format>` eg. `'2014-02-25'` `(accepted range: '1900-01-01' to '2015-12-31')`
* `number` - `<integer_value>` eg. `'13'`
* `currency` - `[<int_value_in_cents>, <currency_code>]` eg. `'[998, USD]'`
* `single` and `multi` - `[<choice_ids>]` eg. `'[1, 2, 4]'`.

  - `workspace.stage` (string)
    The stage of the project. Options are `estimate` and `project`.
    Enum: "estimate", "project"

  - `workspace.require_notes_on_time_entries` (boolean)
    Whether notes are required on time entries logged against this project.

  - `workspace.time_trackable` (boolean)
    Sets whether tasks in the project can have time tracked to them. This field is only usable if allowed by [Time & Expense account settings](https://knowledge.kantata.com/hc/en-us/articles/360000317994-Time-Expense-Settings).

  - `workspace.title` (string)

  - `workspace.archived` (boolean)
    Set to `true` to archive the project or to `false` to unarchive the project.

  - `workspace.price` (integer)
    The project budget, in base units of the currency (e.g. dollars for `USD` ).

  - `workspace.project_template_before_story_id` (integer)
    When `project_tracker_template_id` is provided, the template tasks are inserted after the provided task ID. The provided task ID must belong to an existing and top-level task.

  - `workspace.change_orders_enabled` (boolean)
    Whether approval is required for schedule and budget change orders.

  - `workspace.task_status_set_id` (integer)
    The task status set to assign to the workspace. All stories in the workspace must have a default task status—`not started`, `started`, `needs info`, and `completed`—in their `status` field in order to change the task status set.

## Response 200:

  - `200` (unknown)
    Workspace has been updated.

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

  - `workspaces` (object)

  - `external_references` (object)

  - `stories` (object)

  - `users` (object)

  - `participations` (object)

  - `timesheet_submissions` (object)

  - `workspace_groups` (object)

  - `custom_field_values` (object)

  - `workspace_resources` (object)

  - `status_reports` (object)

  - `account_colors` (object)

  - `account_insights_mappings` (object)

  - `billing_milestones` (object)

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401:

  - `401` (unknown)
    Unauthorized request

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403:

  - `403` (unknown)
    Forbidden request

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404:

  - `404` (unknown)
    Page Not Found

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422:

  - `422` (unknown)
    Unprocessable Entity

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503:

  - `503` (unknown)
    Service is unavailable

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)